Replication Command Forwarding

Alarms > Replication Command Forwarding

Replication Command Forwarding

The Common Alarm Service (CAS) is able to pass or forward commands (such as acknowledgment requests) by writing the commands in XML format to a specified location on the replication server. The CAS will validate the request and if command forwarding is configured, will write out the command and the associated information to an XML file. During startup the CAS will process and delete these files as necessary. A client program such as CygNet Studio or the CAS Alarm Control will receive the same response as if the replicated CAS was not in replicated mode. Replication command forwarding details can be viewed in the service Console screen.

See the following subsections below for more information:

Configuring Replication Command Forwarding
XML File Name Format
XML File Format
Directory Maintenance
Service Console Screen

Configuring Replication Command Forwarding

In order for the CAS to forward a command the following configuration conditions must be met:

The CAS is in replication mode.
The replicated server is configured and running.
The associated CAS service configuration file (Cas.cfg), on the replicated server, has the REPL_FORWARD_DIRECTORY keyword configured, and this will be created during startup if necessary.
The CAS has the ability to write to the directory specified in the REPL_FORWARD_DIRECTORY keyword.
The user sending the request is authorized (has appropriate security) for this request if the service was not in replication mode.
If the Cas.cfg is modified the CAS must be stopped and retarted in order for the changes to take effect.

Upon receiving a validated and authorized request, if the CAS is forwarding commands, the CAS will write the request to the specified directory in the XML format.

Configuration Keywords

The following table contains descriptions for the service configuration keywords required to enable replication command forwarding in the Cas.cfg file.

Keyword	Description
REPL_FORWARD_DIRECTORY	If the service is in replication mode and this keyword is defined, then a setpoint command issued to the source service will be written out as an XML file (ForwardCmds_CVS_Site.Service_######.xml) and saved in the specified directory. Note that setting this keyword does not write the value to the source service. The user will need to evaluate the command and decide whether to modify a point’s current value using a setpoint command on the source service. If this keyword is empty or commented out, then Replication Command Forwarding is disabled. See Replication Command Forwarding for more information.
REPL_FORWARD_MAX_FILES	The maximum number of files in the directory specified by the keyword REPL_FORWARD_DIRECTORY. Once this number is reached, the service will attempt to begin deleting the oldest files. Must be in the range 10-1000. See Replication Command Forwarding for more information.

Keyword

Description

REPL_FORWARD_DIRECTORY

If the service is in replication mode and this keyword is defined, then a setpoint command issued to the source service will be written out as an XML file (ForwardCmds_CVS_Site.Service_######.xml) and saved in the specified directory. Note that setting this keyword does not write the value to the source service. The user will need to evaluate the command and decide whether to modify a point’s current value using a setpoint command on the source service. If this keyword is empty or commented out, then Replication Command Forwarding is disabled. See Replication Command Forwarding for more information.

REPL_FORWARD_MAX_FILES

The maximum number of files in the directory specified by the keyword REPL_FORWARD_DIRECTORY. Once this number is reached, the service will attempt to begin deleting the oldest files. Must be in the range 10-1000. See Replication Command Forwarding for more information.

XML File Name Format

Replication forwarding command file names are designed to support different service types while providing quick identification of the creating service type and name. Forwarded commands will be stored in a file with the following name:

ForwardCmdS_[SERVICE_TYPE]_[SITE.SERVICE]_[SEQUENCE_NUMBER][QUALIFIER].xml

where

[SERVICE_TYPE] is the type of service, in this case "CAS."
[SITE.SERVICE] is the site.service of the CAS.
[SEQUENCE_NUMBER] is a zero-padded numerical number between 000001 and 999999. This will either start at 1 or the next number in the forwarding directory as determined at service startup.
[QUALIFIER] should never appear under normal operations, but if for some reason a file with the next sequence number already exists, this will be added in the form -# where # is a single digit in the range 1-5.

For example:

For a CAS with a name of MYSITE.CAS will create the first command file as: ForwardCmds_CAS_MYSITE.CAS_000001.xml, and the 123rd file as: ForwardCmds_CAS_MYSITE.CAS_000123.xml

If a file with the name ForwardCmds_CAS_MYSITE.CAS_000123.xml already exists, then the file name used would be ForwardCmds_CAS_MYSITE.CAS_000123-1.xml. This should not occur in normal operations.

XML File Format

The XML format used for Replication Command Forwarding is designed to support additional service and command types. The XML takes the following format:

< AlarmRec …/>

< AlarmRec …/>

< AlarmRec …/>

</ForwardingCmds>

ForwardingCmds Node Attributes

This XML node is the root node of the Command Forwarding file.

Attribute	Description	Value Options
CmdType	The type of commands this file contains. Each of this nodes direct child nodes should have this node tag.	CasChangeAlarm is the only supported command for the CAS.
Comment	A comment from the user.	String
FromService	The service creating the file.	[domain]site.service
ServiceType	The service type of the service forwarding the command.	String. For example "CAS for the CAS
TimeStampUTC	The time the XML file was created.	OLE date in floating point format, UTC
ToService	The service the command should be forwarded to.	[domain]site.service
UserId	The User Id of the user that originated the command request.	String

CasChangeAlarm Node Attributes

This XML node is the root node of the CAS Change Alarm command.

Attribute	Description	Value Options
ChangeType	The type of change requested.	String: "ACK", "HIDE", "UNHIDE", "CLEAR", "FORCE"

AlarmRec Node Attributes

This XML node is the root node for the current Alarm Record in the CAS at the time the command was forwarded.

Attribute	Description	Value Options
alarmack	Is the alarm acknowledged?	0 = False, otherwise True
alarmcategory	The alarm category from the point record.	The TRS entry, not the description.
alarmcleared	Is the alarm cleared? (always zero for CAS)	0 = False, otherwise True
alarmpriority	The priority of the alarm.	Numeric: 0-99
alarmprioritycat	The priority category of the alarm.	Numeric: 0-7
alarmrecversion	The version of the alarm record.	Floating point number
facilityid	The facility of the point.	String: Facility Id
hidden	Is the alarm hidden?	0 = False, otherwise True
highestpriority	The highest priority since the point was added to the CAS.	Numeric: 0-99
highestpriorityunack	The highest priority since the point was last acknowledged.	Numeric: 0-99
pointid	The short point id of the point.	String
pointidlong	The long point id of the point.	String
reporttime	The time the alarm was reported to the CAS.	OLE Date in floating point format, UTC
service	The service of the point.	String
setreset	The alarm is set?	0 = Reset, otherwise Set
site	The site of the point.	String
suppression	Is the alarm suppressed?	0 = False, otherwise True
timestamp	The timestamp of the point Realtime record when the alarm was reported to the CAS.	OLE Date in floating point format, UTC
uniformdatacode	The UDC of the point.	String

Directory Maintenance

Upon startup, the CAS will attempt to create the forwarding directory if the service is in replication mode and the REPL_FORWARD_DIRECTORY keyword is configured. This will only be attempted at startup.

The CAS will prevent the number of files in the forwarding directory from growing unbounded. The maximum number of files in this directory is specified in the associated Cas.cfg with the REPL_FORWARD_MAX_FILES keyword.

When the CAS runs its maintenance routine, it will check the number of files in the directory. If the number of files exceeds the maximum number allowed, the CAS will begin to delete the oldest files until the number of files is 10% less than the maximum number of files. The Directory Maintenance routine runs at CAS startup, and after each time a command has been forwarded, unless the routine already been run in the previous 10 minutes.

Service Console Screen

The CAS Service Console Screen (F2: System) provides a visual indication of the forwarding: whether replication command forwarding is configured, the command forwarding directory, the maximum amount of files for the directory, the time of the last command forwarding, and any errors encountered when writing to the directory or during directory maintenance.